
<html><head>
<title>binary_streams - flibs</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.toc,UL.toc UL, UL.toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.section, LI.subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.requirements LI, UL.syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'streams/binstreams.man' by tcllib/doctools with format 'html'
   -->
<! -- Copyright &copy; 2006 Arjen Markus &lt;arjenmarkus@sourceforge.net&gt;
   -->
<! -- CVS: $Id: binstreams.html,v 1.2 2013/05/13 08:03:20 knystrom Exp $ binary_streams.n
   -->
<body><div class="doctools">
<h1 class="title">binary_streams(n) 1.0  &quot;flibs&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>binary_streams - Implement binary streams</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#synopsis">Synopsis</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">DATA TYPES AND ROUTINES</a></li>
<li class="section"><a href="#section3">IMPLEMENTATION NOTES</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
<ul class="syntax">
<li><a href="#1"><b class="cmd">use binary_streams</b></a></li>
<li><a href="#2"><b class="cmd">type(BINARY_STREAM)</b></a></li>
<li><a href="#3"><b class="cmd">call binstream_open( stream, lun, filename, error )</b></a></li>
<li><a href="#4"><b class="cmd">call binstream_close( stream )</b></a></li>
<li><a href="#5"><b class="cmd">call binstream_seek( stream, start, offset )</b></a></li>
<li><a href="#6"><b class="cmd">pos = binstream_tell( stream )</b></a></li>
<li><a href="#7"><b class="cmd">call binstream_read( stream, var, error )</b></a></li>
<li><a href="#8"><b class="cmd">call binstream_write( stream, var, error )</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>The <em>binary_streams</em> module defines a set of subroutines and
functions that allows you to read a file as if it were a &quot;stream&quot;
of bytes, rather than, as is more usual a set of records.</p>
<p>The module uses direct-access file I/O but hides the fact that
you read from individual records. By providing two routines to
query and set the position of the next read/write action and by
automatically positioning a &quot;file pointer&quot; otherwise, the module offers
the benefits of both direct-access files and sequential files.</p>
<p><em>Note:</em> In Fortran 2003, the notion of &quot;streams&quot; is formalised.
This module will be superfluous with compilers supporting Fortran 2003.
Also there are a number of issues that may or may not come into play on
a particular system - see the section on <span class="sectref"><a href="#section3">IMPLEMENTATION NOTES</a></span>.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">DATA TYPES AND ROUTINES</a></h2>
<p>The module defines a single data type, BINARY_STREAM, and several
functions and subroutines:</p>
<dl class="definitions">
<dt><a name="1"><b class="cmd">use binary_streams</b></a></dt>
<dd><p>The name of the module</p></dd>
<dt><a name="2"><b class="cmd">type(BINARY_STREAM)</b></a></dt>
<dd><p>Files are opened and the necessary data are kept in variables of
this type.</p></dd>
<dt><a name="3"><b class="cmd">call binstream_open( stream, lun, filename, error )</b></a></dt>
<dd><p>Open the file &quot;filename&quot; using the LU-number &quot;lun&quot;. If some error
occurs, the argument &quot;error&quot; is set to true.</p>
<dl class="arguments">
<dt>type(binary_stream) <i class="arg">stream</i></dt>
<dd><p>The variable by which to reference the file</p></dd>
<dt>integer, intent(in) <i class="arg">lun</i></dt>
<dd><p>The LU-number to connect the file to</p></dd>
<dt>character(len=*), intent(in) <i class="arg">filename</i></dt>
<dd><p>The name of the file to open</p></dd>
<dt>logical, intent(out) <i class="arg">error</i></dt>
<dd><p>Argument indicating whether opening the file was successful or not.
Note that the file is opened with read/write access (though not
explicitly) and that it is opened in such a way that the record length
is 4 bytes. If this is not possible (for any number of reasons), an
error is returned.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">call binstream_close( stream )</b></a></dt>
<dd><p>Close the file that was opened as a stream.</p>
<dl class="arguments">
<dt>type(binary_stream) <i class="arg">stream</i></dt>
<dd><p>The variable by which to reference the file</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">call binstream_seek( stream, start, offset )</b></a></dt>
<dd><p>Set the position in the file (either from the start or from the current
position).</p>
<dl class="arguments">
<dt>type(binary_stream) <i class="arg">stream</i></dt>
<dd><p>The variable by which to reference the file</p></dd>
<dt>logical, intent(in) <i class="arg">start</i></dt>
<dd><p>If true, the offset is from the start of the file. Otherwise it is an
offset from the current position.</p></dd>
<dt>integer, intent(in) <i class="arg">offset</i></dt>
<dd><p>The number of bytes to skip from the given position. Zero means either
the start of the file or the same position.</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">pos = binstream_tell( stream )</b></a></dt>
<dd><p>Return the current position in the file (in bytes, the first byte is
taken as 0).</p>
<dl class="arguments">
<dt>type(binary_stream) <i class="arg">stream</i></dt>
<dd><p>The variable by which to reference the file</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">call binstream_read( stream, var, error )</b></a></dt>
<dd><p>Read a variable &quot;var&quot; from the current position in the file.</p>
<dl class="arguments">
<dt>type(binary_stream) <i class="arg">stream</i></dt>
<dd><p>The variable by which to reference the file</p></dd>
<dt>(...), intent(out) <i class="arg">var</i></dt>
<dd><p>The variable to be read. It can be either a character string, a
(default) integer, a (default) real, a (default) logical or a
double-precision real. Also one- and two-dimensional arrays of these
types are supported.</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">call binstream_write( stream, var, error )</b></a></dt>
<dd><p>Write a variable &quot;var&quot; at the current position in the file.</p>
<dl class="arguments">
<dt>type(binary_stream) <i class="arg">stream</i></dt>
<dd><p>The variable by which to reference the file</p></dd>
<dt>(...), intent(in) <i class="arg">var</i></dt>
<dd><p>The variable to be written. It can be either a character string, a
(default) integer, a (default) real, a (default) logical or a
double-precision real. Also one- and two-dimensional arrays of these
types are supported.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="section"><h2><a name="section3">IMPLEMENTATION NOTES</a></h2>
<p>The module makes a number of assumptions:</p>
<ul class="itemized">
<li><p>Any file can be opened as a direct-acess file with any
record length</p></li>
<li><p>To avoid complicated code the files are opened with
records of 4 bytes long (ordinary the record length is 4
or 1 - the length unit is system-dependent!). This means
that systems where the unit is not 1 or 4 bytes are not
supported - this could include 64-bits systems.</p></li>
<li><p>The end of a file may not be accurately detected. This
is due to the behaviour of direct-access files: the
last record may not be complete, if the file size is
a multiple of 4 bytes.</p></li>
<li><p>A default integer is assumed to be 4 bytes, as is
a default real and a default logical. A double precision
real is assumed to be 8 bytes long. There is NO provision
for situations where this is not true.</p></li>
</ul>
</div>
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2006 Arjen Markus &lt;arjenmarkus@sourceforge.net&gt;</p>
</div>
</div></body></html>